<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Syntax and conditional compilation</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Overall-Index.xhtml" title="Index"/>
    <link rel="next" href="Macros.xhtml" title="Macros"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Syntax and conditional compilation" epub:type="subchapter" id="Syntax-and-conditional-compilation">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Syntax and conditional compilation</h2>
          </div>
        </div>
      </div>
      <h3 id="idm139667879083936">Feature testing</h3>
      <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667879083120" class="indexterm"/> <code class="function">cond-expand</code> <em class="replaceable"><code><a class="link" href="Syntax-and-conditional-compilation.xhtml#meta-cond-expand-clause"><em class="replaceable"><code>cond-expand-clause</code></em></a></code></em><em class="replaceable"><code><sup>*</sup></code></em> [<em class="replaceable"><code><span class="bold"><strong>(else</strong></span></code></em> <em class="replaceable"><code>command-or-definition*</code></em><em class="replaceable"><code><span class="bold"><strong>)</strong></span></code></em>]</p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <div class="literallayout">
            <p><a id="idm139667879077232" class="indexterm"/><span id="meta-cond-expand-clause"/><em class="replaceable"><code>cond-expand-clause</code></em> <code class="literal">::=</code> <code class="literal"><span class="bold"><strong>(</strong></span></code><em class="replaceable"><code>feature-requirement</code></em> <em class="replaceable"><code>command-or-definition</code></em>*<code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
<a id="idm139667879072976" class="indexterm"/><a id="idm139667879072192" class="indexterm"/><span id="meta-feature-requirement"/><em class="replaceable"><code>feature-requirement</code></em> <code class="literal">::=</code> <a class="link" href="Syntax-and-conditional-compilation.xhtml#meta-feature-identifier"><em class="replaceable"><code>feature-identifier</code></em></a><br/>
  | <code class="literal"><span class="bold"><strong>(and</strong></span></code> <a class="link" href="Syntax-and-conditional-compilation.xhtml#meta-feature-requirement"><em class="replaceable"><code>feature-requirement</code></em></a><sup>*</sup><code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
  | <code class="literal"><span class="bold"><strong>(or</strong></span></code> <a class="link" href="Syntax-and-conditional-compilation.xhtml#meta-feature-requirement"><em class="replaceable"><code>feature-requirement</code></em></a><sup>*</sup><code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
  | <code class="literal"><span class="bold"><strong>(not</strong></span></code> <a class="link" href="Syntax-and-conditional-compilation.xhtml#meta-feature-requirement"><em class="replaceable"><code>feature-requirement</code></em></a><code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
  | <code class="literal"><span class="bold"><strong>(library</strong></span></code> <a class="link" href="Module-classes.xhtml#meta-library-name"><em class="replaceable"><code>library-name</code></em></a><code class="literal"><span class="bold"><strong>)</strong></span></code><br/>
<a id="idm139667879059520" class="indexterm"/><span id="meta-feature-identifier"/><em class="replaceable"><code>feature-identifier</code></em> <code class="literal">::=</code> a symbol which is the name or alias of a SRFI<br/>
</p>
          </div>
          <p>The <code class="literal">cond-expand</code> form tests for the existence of features at
macro-expansion time. It either expands into the body of one of its
clauses or signals an error during syntactic
processing. <code class="literal">cond-expand</code> expands into the body of the first clause
whose feature requirement is currently satisfied; the <code class="literal">else</code>
clause, if present, is selected if none of the previous clauses is
selected.
</p>
          <p>The implementation has a set of
feature identifiers which are “present”, as well as a set
of libraries which can be imported.
The value of a
<em class="replaceable"><code>feature-requirement</code></em> is determined by replacing each
<em class="replaceable"><code>feature-identifier</code></em> by <code class="literal">#t</code> if it is present
(and <code class="literal">#f</code> otherwise);
replacing <code class="literal">(library <em class="replaceable"><code>library-name</code></em>)</code>
by <code class="literal">#t</code> if <em class="replaceable"><code>library-name</code></em> is importable (and <code class="literal">#f</code> otherwise);
and then evaluating the resulting expression as a Scheme boolean expression
under the normal interpretation of <code class="literal">and</code>, <code class="literal">or</code>, and <code class="literal">not</code>.
</p>
          <p>Examples:
</p>
          <pre class="screen">(cond-expand
    ((and srfi-1 srfi-10)
     (write 1))
    ((or srfi-1 srfi-10)
     (write 2))
    (else))
</pre>
          <pre class="screen">(cond-expand
  (command-line
   (define (program-name) (car (argv)))))
</pre>
          <p>The second example assumes that <code class="literal">command-line</code> is an alias for some
feature which gives access to command line arguments. Note that an error
will be signaled at macro-expansion time if this feature is not present.
</p>
          <p>You can use <code class="literal">java-6</code>, <code class="literal">java-7</code>, <code class="literal">java-8</code>,
or <code class="literal">java-9</code> to check if the underlying Java
is a specific version or newer.
For example the name <code class="literal">java-7</code> matches for
either Java 7, Java 8, or newer, as
reported by <code class="literal">System</code> property <code class="literal">"java.version"</code>.
</p>
          <p>You can use <code class="literal">class-exists:<em class="replaceable"><code>ClassName</code></em></code> to check
if <code class="literal"><em class="replaceable"><code>ClassName</code></em></code> exists at compile-time.
The identifier <code class="literal">class-exists:org.example.MyClass</code>
is roughly equivalent to the test <code class="literal">(library (org example MyClass))</code>.
(The latter has some special handling for <code class="literal">(srfi ...)</code> as well
as builtin Kawa classes.)
</p>
        </blockquote>
      </div>
      <p class="synopsis" kind="Procedure"><span class="kind">Procedure</span><span class="ignore">: </span><a id="idm139667879040080" class="indexterm"/> <code class="function">features</code></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>Returns a list of feature identifiers which <code class="literal">cond-expand</code>
treats as true.
This not a complete list - for example <code class="literal">class-exists:<em class="replaceable"><code>ClassName</code></em></code>
feature identifiers are not included.
It is an error to modify this list.
Here is an example of what <code class="literal">features</code> might return:
</p>
          <pre class="screen">(features)  ⇒
(complex exact-complex full-unicode java-7 java-6 kawa
 ratios srfi-0 srfi-4 srfi-6 srfi-8 srfi-9 srfi-11
 srfi-16 srfi-17 srfi-23 srfi-25 srfi-26 srfi-28 srfi-30
 srfi-39 string-normalize-unicode threads)
</pre>
        </blockquote>
      </div>
      <h3 id="idm139667879034704">File inclusion</h3>
      <span id="include"/>
      <span id="include-relative"/>
      <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667879033088" class="indexterm"/> <code class="function">include</code> <em class="replaceable"><code>path</code></em><em class="replaceable"><code><sup>+</sup></code></em></p>
      <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667879029872" class="indexterm"/> <code class="function">include-relative</code> <em class="replaceable"><code>path</code></em><em class="replaceable"><code><sup>+</sup></code></em></p>
      <p class="synopsis" kind="Syntax"><span class="kind">Syntax</span><span class="ignore">: </span><a id="idm139667879026656" class="indexterm"/> <code class="function">include-ci</code> <em class="replaceable"><code>path</code></em><em class="replaceable"><code><sup>+</sup></code></em></p>
      <div class="blockquote">
        <blockquote class="blockquote">
          <p>These take one or more path names expressed as string literals,
find corresponding files, read the contents of the files in the specified order
as if by repeated applications of <code class="literal">read</code>, and effectively
replace the <code class="literal">include</code> with a <code class="literal">begin</code> form
containing what was read from the files.
</p>
          <p>You can control the search path used for <code class="literal">include</code>
by setting the <code class="literal">kawa.include.path</code> property.  For example:
</p>
          <pre class="screen">$ kawa -Dkawa.include.path="|:/opt/kawa-includes"
</pre>
          <p>The special <code class="literal">"|"</code> path element means to search
relative to the directory containing the including source file.
The default search path is <code class="literal">"|:."</code> which means to first
search the directory containing the including source file,
and then search the directory specified by <code class="literal">(current-path)</code>.
</p>
          <p>The search path for <code class="literal">include-relative</code> prepends <code class="literal">"|"</code>
before the search path used by <code class="literal">include</code>, so it always
searches first the directory containing the including source file.
Note that if the default search path is used then <code class="literal">include</code>
and <code class="literal">include-relative</code> are equivalent; there is only a difference
if the <code class="literal">kawa.include.path</code> property changes the default.
</p>
          <p>Using <code class="literal">include-ci</code> is like <code class="literal">include</code>, except that it reads each
file as if it began with the <code class="literal">#!fold-case</code> directive.
</p>
        </blockquote>
      </div>
    </section>
    <footer>
      <div class="navfooter">
        <p>
          Up: <a accesskey="u" href="Syntax.xhtml">Syntax</a></p>
        <p>
        Previous: <a accesskey="p" href="Bodies.xhtml">Programs and Bodies</a></p>
        <p>
        Next: <a accesskey="n" href="Macros.xhtml">Macros</a></p>
      </div>
    </footer>
  </body>
</html>
